Skip to content

feat(liquidity): add LayerZero bridge adapter for Ethereum->Citrea bridging #3054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
TaprootFreak merged 9 commits into from
Jan 30, 2026
Merged

feat(liquidity): add LayerZero bridge adapter for Ethereum->Citrea bridging #3054

TaprootFreak merged 9 commits into from
Jan 30, 2026
+397 −1

Conversation

@TaprootFreak
Copy link
Collaborator

@TaprootFreak TaprootFreak commented Jan 27, 2026 •
edited
Loading

Summary

This PR adds LayerZero OFT (Omnichain Fungible Token) bridge support to the liquidity management system, enabling automated bridging of USDC, USDT, and WBTC from Ethereum Mainnet to Citrea.

Background

LayerZero is a cross-chain messaging protocol that enables seamless token transfers between blockchains. The OFT standard allows tokens to be transferred across chains while maintaining fungibility. This integration enables DFX to automatically bridge liquidity to Citrea when needed.

Changes

New Files

  • src/integration/blockchain/shared/evm/abi/layerzero-oft-adapter.abi.json - ABI for LayerZero OFT adapter contracts
  • src/subdomains/core/liquidity-management/adapters/actions/layerzero-bridge.adapter.ts - Bridge adapter implementation

Modified Files

  • src/subdomains/core/liquidity-management/enums/index.ts - Added LAYERZERO_BRIDGE enum
  • src/subdomains/core/liquidity-management/factories/liquidity-action-integration.factory.ts - Registered adapter
  • src/subdomains/core/liquidity-management/liquidity-management.module.ts - Added provider

Implementation Details

Supported Tokens & Contract Addresses

Token Ethereum OFT Adapter Citrea Destination
USDC 0xdaa289CC487Cf95Ba99Db62f791c7E2d2a4b868E 0x41710804caB0974638E1504DB723D7bddec22e30
USDT 0x6925ccD29e3993c82a574CED4372d8737C6dbba6 0xF8b5983BFa11dc763184c96065D508AE1502C030
WBTC 0x2c01390E10e44C968B73A7BcFF7E4b4F50ba76Ed 0xDF240DC08B0FdaD1d93b74d5048871232f6BEA3d

Supported Commands

  • deposit - Bridge tokens from Ethereum to Citrea

Bridge Flow

1. Validate target asset is TOKEN type
2. Map Citrea token name to base token (e.g., USDC.e → USDC)
3. Lookup corresponding Ethereum asset
4. Check Ethereum token balance
5. Ensure token approval for OFT adapter
6. Quote LayerZero messaging fee
7. Verify sufficient ETH for fee + gas
8. Execute OFT send transaction
9. Return TX hash as correlation ID

Completion Check

1. Verify Ethereum TX receipt exists
2. Check TX status (throw OrderFailedException if failed)
3. Query Citrea token balance
4. Compare against expected output amount

Error Handling

Scenario Exception Type
Unsupported asset type OrderNotProcessableException
Token not configured OrderNotProcessableException
Ethereum asset not found OrderNotProcessableException
Insufficient token balance OrderNotProcessableException
Insufficient ETH for fees OrderNotProcessableException
Token approval failed OrderFailedException
Bridge TX failed OrderFailedException
Ethereum TX failed (in checkCompletion) OrderFailedException

Configuration

  • Citrea LayerZero Endpoint ID: 30291
  • Slippage Tolerance: 1%
  • Gas Limit: 500,000 (conservative estimate for OFT transfers)

Known Limitations

  1. Completion Detection: Uses balance heuristic rather than LayerZero message GUID tracking. If wallet has pre-existing balance, completion may be detected early.
  2. Unidirectional: Only supports Ethereum → Citrea (no withdraw command yet)
  3. No Retry Logic: Transient failures are not automatically retried

Future Improvements

  • Integrate LayerZero Scan API for precise message tracking
  • Add withdraw command for Citrea → Ethereum
  • Dynamic gas estimation
  • Configurable slippage tolerance

Test Plan

  • TypeScript compilation passes
  • Prettier formatting passes
  • Test deposit with small USDC amount
  • Verify token approval flow
  • Confirm LayerZero fee calculation
  • Test checkCompletion after successful bridge
  • Test error handling for insufficient balance
  • Test error handling for insufficient ETH

@TaprootFreak
feat(liquidity): add LayerZero bridge adapter for Ethereum->Citrea br…
f0407a3 
…idging

Add support for bridging USDC, USDT, and WBTC from Ethereum to Citrea
using LayerZero OFT (Omnichain Fungible Token) protocol.

- Add LAYERZERO_BRIDGE to LiquidityManagementSystem enum
- Create LayerZeroBridgeAdapter with deposit command
- Add LayerZero OFT adapter ABI (quoteSend, send, approvalRequired)
- Configure OFT adapter addresses for USDC, USDT, WBTC
- Support token approval and fee quoting
TaprootFreak and others added 8 commits January 27, 2026 02:14
@TaprootFreak
fix(liquidity): improve LayerZero adapter robustness
f2eb61d 
- Fix validateParams to handle undefined params
- Fix quoteSend return value (returns tuple, not array)
- Improve checkCompletion with better error handling and logging
- Add output amount verification in completion check
@TaprootFreak
style: fix prettier formatting
c6d5cea
@TaprootFreak
refactor(liquidity): align LayerZero adapter with codebase conventions
03b3ae1 
- Export LayerZeroBridgeCommands enum (consistent with other adapters)
- Use switch statement in validateParams (consistent with DfxDexAdapter)
- Throw error for unknown commands (consistent with other adapters)
@TaprootFreak
fix(liquidity): improve LayerZero adapter professionalism
7e63b69 
- Throw OrderFailedException for failed Ethereum TX (not just return false)
- Add ETH balance check before bridge execution
- Extract token approval into separate method with proper error handling
- Re-throw OrderFailedException in checkCompletion (don't swallow it)
- Add logging for approval confirmation
- Add detailed error messages for insufficient funds
@TaprootFreak
refactor(liquidity): align LayerZero adapter with existing bridge pat…
befab43 
…terns

- Remove unnecessary service storage (only store clients, like ArbitrumL2BridgeAdapter)
- Align checkCompletion error handling with EvmL2BridgeAdapter (throw OrderFailedException)
- Simplify validateParams to match EvmL2BridgeAdapter pattern (return true)
@TaprootFreak
fix(liquidity): prevent double-wrapping OrderFailedException in approval
643544a
@davidleomay
Merge branch 'develop' into feat/layerzero-bridge-integration
887a582
@davidleomay
chore: refactoring/fixes
027dc58
@TaprootFreak TaprootFreak merged commit 27cf474 into develop Jan 30, 2026
7 checks passed
@TaprootFreak TaprootFreak deleted the feat/layerzero-bridge-integration branch January 30, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@davidleomay davidleomay davidleomay approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@TaprootFreak @davidleomay